
<h1 id="toc0"> Contact Form Component.</h1>
<p>This component is probably the simplest contact form component in <a href="http://joomla.org/" onclick="window.open(this.href, '_blank'); return false;">Joomla</a> 1.5. It's just a form that sends it's contents to the specified email address. If you don't need a form builder, special fields or fancy configuration but you want something that's easy to modify and renders as fast as possible this is the contact form you where looking for.</p>


<h2 id="toc1"> Installation.</h2>
<p>If you haven't already downloaded the <a href="http://code.google.com/p/joomphase/" onclick="window.open(this.href, '_blank'); return false;">com_contact_X.XX.zip</a> archive go do that now. I'll wait.</p>

<p>Done? Now, open your website's administration and from the menu select <tt>Extensions / Install &amp; Uninstall</tt>. In the <tt>Upload Package File</tt> section click the <tt>Browse</tt> button and locate the com_contact_X.XX.zip archive. Then click the <tt>Upload File &amp; Install</tt> button.</p>

<p><strong>IMPORTANT: Don't forget to configure your email address or all the emails will end up on <a href="http://mailinator.com/" onclick="window.open(this.href, '_blank'); return false;">Mailinator</a> by default.</strong></p>


<h2 id="toc2"> Configuration.</h2>
<p>You need to setup the e-mail address that will receive the information posted on the form and, optionally, a prefix for the subject line that will make it easy to setup rules on your email client.</p>

<p>To do this, enter to your website's administration and select <tt>Components / Contact Form</tt> from the menu. Click the <tt>Preferences</tt> button on the toolbar and change those values. Finally, click the <tt>Save</tt> button.</p>

<p>Now, create a new Menu Item and from the list of Menu Item Types select "Contact Form". That's it, your contact form should be operational by now.</p>

<p>You can create aditional contact forms by creating other Menu Items and they can even send their emails to another email address. Just take a look at the "Parameters - Component" side bar when creating the Menu Item and change what ever you want there.</p>


<h2 id="toc3"> Customizing.</h2>
<p>Depending on what you have in mind customizing the component can be simply a matter of changing the template's CSS or it might need modification of the php source files.</p>


<h3 id="toc4"> Modifying the appearance of the form.</h3>
<p>You can modify the form's appearance simply by adding CSS rules to your templates. The form is marked with a <tt>id=&quot;ContactForm<a class="" href="http://example.com/new.php?page=ContactForm">?</a>&quot;</tt> to allow referring to it's elements easily. For example, if you want the names of the fields to appear in color blue you can do the following:</p>


<pre><code>
#ContactForm label {
    color: blue;
}</code></pre>

<p>And if you want to refer to the fields themselves just use the following rule:</p>


<pre><code>
#ContactForm input,
#ContactForm textarea {
    border: 2px inset;
}</code></pre>

<p>Now, if you really want complete control over the generated HTML simply open and modify what ever you want from the <tt>com_contactform/views/contactform/tmpl/default.php</tt> layout file.</p>


<h3 id="toc5"> Adding custom fields.</h3>
<p>I wanted to keep this component as simple as possible so I didn't add a form builder as other components have. This means that adding custom fields involves some programming but, as you'll see, it's not too difficult and only two files need to be modified.</p>

<p>Let's add a simple field that asks the user for it's country of residence. The first thing you have to do is add the field to the HTML form. This is done in the <tt>com_contactform/views/contactform/tmpl/default.php</tt> file:</p>


<pre><code>&lt;html&gt;

    (...)
    &lt;table cellspacing=&quot;0&quot; cellpadding=&quot;0&quot; border=&quot;0&quot; width=&quot;100%&quot;&gt;
        &lt;tbody&gt;
            &lt;tr&gt;
                &lt;th&gt;&lt;label for=&quot;cfCountry&quot;&gt;&lt;?php echo JText::_('Country') ?&gt;:&lt;/label&gt;&lt;/th&gt;
                &lt;td&gt;&lt;select id=&quot;cfCountry&quot; name=&quot;country&quot;&gt;
                    &lt;option&gt;Aaland Islands&lt;/option&gt;
                    &lt;option&gt;Afghanistan&lt;/option&gt;
                    &lt;option&gt;Albania&lt;/option&gt;
                    &lt;option&gt;Algeria&lt;/option&gt;
                    &lt;option&gt;American Samoa&lt;/option&gt;
                    (...)
                &lt;/select&gt;&lt;/td&gt;
            &lt;/tr&gt;
            &lt;tr&gt;
                &lt;th&gt;&lt;label for=&quot;cfName&quot;&gt;&lt;?php echo JText::_('CF_FIELD_NAME') ?&gt;:&lt;/label&gt;&lt;/th&gt;
                &lt;td&gt;&lt;input class=&quot;inputbox&quot; id=&quot;cfName&quot; name=&quot;name&quot; type=&quot;text&quot; maxlength=&quot;100&quot;
                value=&quot;&lt;?php echo $this-&gt;escape($this-&gt;model-&gt;name) ?&gt;&quot;/&gt;&lt;/td&gt;
    (...)
&lt;/html&gt;</code></pre>

<p>Now the form is sending an extra value named &quot;country&quot; that contains the name of the selected country. Let's read that value in the model <tt>com_contactform/models/contactform.php</tt> file:</p>


<pre><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php

    </span><span style="color: #007700">(...)
    var </span><span style="color: #0000BB">$country </span><span style="color: #007700">= </span><span style="color: #DD0000">''</span><span style="color: #007700">;
    var </span><span style="color: #0000BB">$name </span><span style="color: #007700">= </span><span style="color: #DD0000">''</span><span style="color: #007700">;
    var </span><span style="color: #0000BB">$email </span><span style="color: #007700">= </span><span style="color: #DD0000">''</span><span style="color: #007700">;
    var </span><span style="color: #0000BB">$subject </span><span style="color: #007700">= </span><span style="color: #DD0000">''</span><span style="color: #007700">;
    var </span><span style="color: #0000BB">$message </span><span style="color: #007700">= </span><span style="color: #DD0000">''</span><span style="color: #007700">;

    function </span><span style="color: #0000BB">send</span><span style="color: #007700">()
    {
        </span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">country  </span><span style="color: #007700">= </span><span style="color: #0000BB">JMailHelper</span><span style="color: #007700">::</span><span style="color: #0000BB">cleanLine</span><span style="color: #007700">(</span><span style="color: #0000BB">JRequest</span><span style="color: #007700">::</span><span style="color: #0000BB">getString</span><span style="color: #007700">(</span><span style="color: #DD0000">'country'</span><span style="color: #007700">, </span><span style="color: #DD0000">''</span><span style="color: #007700">));
        </span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">name     </span><span style="color: #007700">= </span><span style="color: #0000BB">JMailHelper</span><span style="color: #007700">::</span><span style="color: #0000BB">cleanLine</span><span style="color: #007700">(</span><span style="color: #0000BB">JRequest</span><span style="color: #007700">::</span><span style="color: #0000BB">getString</span><span style="color: #007700">(</span><span style="color: #DD0000">'name'</span><span style="color: #007700">, </span><span style="color: #DD0000">''</span><span style="color: #007700">));
    (...)
</span><span style="color: #0000BB">?&gt;</span>
</span></code></pre>

<p>If the field is required then we should add validation for it, if not just skip this step:</p>


<pre><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php

    </span><span style="color: #007700">(...)
    if (</span><span style="color: #DD0000">'' </span><span style="color: #007700">== </span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">country</span><span style="color: #007700">)
    {
        </span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">setError</span><span style="color: #007700">(</span><span style="color: #DD0000">'Please enter your Country.'</span><span style="color: #007700">);
        return </span><span style="color: #0000BB">false</span><span style="color: #007700">;
    }
    if (</span><span style="color: #DD0000">'' </span><span style="color: #007700">== </span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">name</span><span style="color: #007700">)
    {
    (...)
</span><span style="color: #0000BB">?&gt;</span>
</span></code></pre>

<p>And just before sending the email we add it to the body of the message:</p>


<pre><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php

    </span><span style="color: #007700">(...)
    </span><span style="color: #0000BB">$body </span><span style="color: #007700">= </span><span style="color: #0000BB">JText</span><span style="color: #007700">::</span><span style="color: #0000BB">_</span><span style="color: #007700">(</span><span style="color: #DD0000">'CF_FIELD_NAME'</span><span style="color: #007700">) . </span><span style="color: #DD0000">': ' </span><span style="color: #007700">. </span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">name
        </span><span style="color: #007700">. </span><span style="color: #DD0000">"\r\n" </span><span style="color: #007700">. </span><span style="color: #0000BB">JText</span><span style="color: #007700">::</span><span style="color: #0000BB">_</span><span style="color: #007700">(</span><span style="color: #DD0000">'CF_FIELD_EMAIL'</span><span style="color: #007700">) . </span><span style="color: #DD0000">': ' </span><span style="color: #007700">. </span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">email
        </span><span style="color: #007700">. </span><span style="color: #DD0000">"\r\nCountry = $this-&gt;country"</span><span style="color: #007700">;
        . </span><span style="color: #DD0000">"\r\n\r\n$this-&gt;message"</span><span style="color: #007700">;
        
    </span><span style="color: #0000BB">jimport</span><span style="color: #007700">(</span><span style="color: #DD0000">'joomla.utilities.utility'</span><span style="color: #007700">);

    return </span><span style="color: #0000BB">JUtility</span><span style="color: #007700">::</span><span style="color: #0000BB">sendMail</span><span style="color: #007700">(</span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">email</span><span style="color: #007700">, </span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">name</span><span style="color: #007700">, </span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">_recipient</span><span style="color: #007700">, </span><span style="color: #DD0000">"$this-&gt;_prefix $this-&gt;subject"</span><span style="color: #007700">,
        </span><span style="color: #0000BB">$body</span><span style="color: #007700">, </span><span style="color: #0000BB">false</span><span style="color: #007700">);
    (...)
</span><span style="color: #0000BB">?&gt;</span>
</span></code></pre>

<p>That's it. The new field is now working.</p>

<dl>
    <dt>Author</dt>
        <dd>Julio C&eacute;sar Carrascal Urquijo</dd>
    <dt>Last Modification</dt>
        <dd>$Date: 2007-11-03 03:51:14 +0000 (Sat, 03 Nov 2007) $</dd>
    <dt>Source Copyright</dt>
        <dd>GNU/LGPL</dd>
    <dt>Documentation Copyright</dt>
        <dd>GNU/FDL</dd>
</dl>
